Web API Common Features

Some aspects of the Web APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request and response formats are consistent across all endpoints. This includes a small set of HTTP headers, HTTP statuses returned by the server for successful requests, and various error conditions. Common request headers are given in Table 62: Common Request Headers, common response headers (for successful requests and certain unsuccessful requests) are given in Table 63: Common Response Headers, and HTTP statuses are given in Table 64: HTTP Statuses.

Additionally, many Classic APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. methods operate on a certificate resource stored in Keyfactor Command, and a standardized way to identify the certificate for the operation is used in the request structure across several Classic API components; this is described in Table 65: Classic API Certificate Lookup Structure. This table does not apply to the Keyfactor API.

Table 62: Common Request Headers

Header Name

 API Version

Header Value

Description

Content-Type

 Both

application/json

OR

application/xml

POST methods use application/json. When application/xml is needed, it is specifically indicated on the endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. page.

Accept

 Both

application/json; charset=utf-8

Most methods returning complex values will use this content type.

Authorization

 Both

Basic <base-64 DOMAIN\user:pass>

In most cases, Web API clients will use Basic authentication over SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers./TLSClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers..

Host

 Both

<Keyfactor Command server hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername).>

Address of Keyfactor Command server. Automatically generated in most clients.

Content-Length

 Both

Request length in bytes

Optional, but automatically generated by most clients.

X-Keyfactor-Requested-With

 Both

XMLHttpRequest

This is mandatory to send in a request to the Keyfactor API on POSTs, PUTs, and DELETEs, and the value is case sensitive. This is for security.
X-Keyfactor-API-Version Keyfactor API 1 or 2 Desired version of the endpoint. If not provided, this defaults to version 1.

Table 63: Common Response Headers

Header Name

 API Version

Header Value

Description

Cache-Control

 Both

no-cache

API requests are generally not cacheable. Note that this is not respected by all client systems.

Pragma

 Both

no-cache

API requests are generally not cacheable. Note that this is not respected by all client systems.

Content-Length

 Both

<varies>

Length of the HTTP response.

Content-Type

 Both

application/json

Most calls return application/json, but occasionally text/plain or text/xml.

Expires

 Both

-1

Usually ignored.

Server

 Both

<varies>

Software version reported by IIS platform hosting Keyfactor Command.

X-CSS-CMS-APIVersion

 Classic API

2.0

Classic API version accessed (see usage in Versioning).

X-CSS-CMS-CMSVersion

 Classic API

10.2

Keyfactor Command platform version.
X-Keyfactor-Product-Version Keyfactor API <varies> Keyfactor Command platform version.

X-Total-Count

 Keyfactor API

<varies>

Total number of elements returned.

X-AspNet-Version

 Both

<varies>

Version of ASP.NET supporting Keyfactor Command installation.

X-Powered-By

 Both

ASP.NET

Header added by underlying ASP.NET implementation.

Date

 Both

<varies>

Timestamp of the HTTP response.

Table 64: HTTP Statuses

Number/Name

Description

200 OK

Request successful; results in response body

204 No Content

Request successful; no content in response body

400 Bad Request

Malformed or invalid data; additional information may be available in the response body and/or Keyfactor Command server logs

401 Unauthorized

Invalid credentials (user unauthenticated)

403 Forbidden

Can often indicate that the credentials map to a user without permissions for this action in Keyfactor Command (user unauthorized)

404 Page not Found

Invalid request path

500 Internal Server Error

Keyfactor Command encountered an unexpected error attempting to handle the request. See response body and Keyfactor Command server logs for details.

502 Bad Gateway

Keyfactor Command attempted to contact a CAClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. or other upstream server to process the request, but was unable to. See Keyfactor Command server logs for details.

Table 65: Classic API Certificate Lookup Structure

Parameter Name

Parameter Value

Type

One of "Serial", "Thumbprint", and "CMSID".

SerialNumber

Hexadecimal serial number of referenced certificate. Required only if Type is "Serial".

IssuerDN

Distinguished Name of the issuer of the referenced certificate. Required only if Type is "Serial".

Thumbprint

SHA-1 thumbprint of the referenced certificate. Required only if Type is "Thumbprint".

CMSID

Identifier assigned by Keyfactor Command to the referenced certificate. Required only if Type is "CMSID".